HiRISE JP2 Fix Tool

Fix GeoJP2 projection parameters in HiRISE equirectangular images

Overview

fix_jp2_v2 is a specialized utility that corrects malformed GeoTIFF projection metadata in HiRISE (High Resolution Imaging Science Experiment) JPEG2000 files. It specifically fixes Equirectangular projections that were incorrectly encoded with CenterLatGeoKey instead of StandardParallel1GeoKey.

This tool performs in-place binary editing of GeoJP2 headers without decompressing or recompressing the imagery, making it extremely fast.

The Problem

Historically, some HiRISE GeoJP2 files were generated with incorrect GeoTIFF projection parameters for Equirectangular projections. According to the GeoTIFF specification:

• Incorrect: Using CenterLatGeoKey (tag 3089)
• Correct: Using StandardParallel1GeoKey (tag 3078)

This discrepancy caused projection misinterpretation in GDAL and other GIS software.

As of version 2 (January 2023), this tool will not modify files that already have correct StandardParallel1GeoKey tags. The HiRISE team has updated their processing pipeline.

Related Issue

GDAL Ticket #2706

Installation

Pre-compiled Windows Executable

A Windows executable (fix_jp2_v2.exe) is included in the repository:

~/workspace/source/HiRISE_fix_jp2/fix_jp2_v2.exe

Use from any Windows command-line terminal (cmd, PowerShell).

Compile from Source

On Linux, macOS, or Windows with GCC:

g++ -o fix_jp2_v2 fix_jp2_v2.cpp

No external libraries required - uses only standard C/C++ libraries.

Usage

fix_jp2_v2 HiRISE_targetfile.jp2

Parameters

targetfile.jp2 · string · required

Path to the HiRISE JPEG2000 file to fix. The file is modified in-place.

How It Works

1. Locate GeoTIFF Header

   Scans the first 10KB of the JP2 file for the embedded TIFF header within the UUID box.

2. Find GeoKey Directory

   Locates the GEOKEYDIRECTORY tag (34735) containing projection parameters.

3. Check for Existing Fix

   Searches for StandardParallel1GeoKey (3078). If found, exits without changes.

4. Locate CenterLatGeoKey

   Finds the incorrect CenterLatGeoKey (3089) tag.

5. Binary Edit

   Replaces tag 3089 bytes with 3078 bytes in the file header.

6. Verify and Report

   Confirms successful write and reports “Success, file updated.”

Examples

Fix Single File

fix_jp2_v2 ESP_012345_1234_RED.JP2

Output (if needs fixing):

Success, file updated.

Output (if already correct):

WARNING: tag (3078 / StdParallel1GeoKey already exists). No change will be made - exiting.

Batch Processing

Linux/macOS:

for file in *.JP2; do
  echo "Processing $file"
  fix_jp2_v2 "$file"
done

Windows (PowerShell):

Get-ChildItem *.JP2 | ForEach-Object {
  Write-Host "Processing $_"
  .\fix_jp2_v2.exe $_.FullName
}

Verify Fix with GDAL

Before:

gdalinfo ESP_012345_1234_RED.JP2 | grep -A 5 "PROJECTION"

After:

gdalinfo ESP_012345_1234_RED.JP2 | grep -A 5 "PROJECTION"

Look for standard_parallel_1 parameter in the output.

Technical Details

File Format Constraints

Little-Endian Only: This tool only works on little-endian TIFF/GeoTIFF data. Big-endian files are detected but may not be processed correctly.

• GeoTIFF data must be within the first 10KB of the JP2 file
• Does not validate that the file actually uses Equirectangular projection
• Does not modify image data or recompress JPEG2000 stream

What Gets Modified

Only 2 bytes in the GeoKey directory are changed:

Tag 3089 (0x0C11) → Tag 3078 (0x0C06)

All other projection parameters (standard parallel value, central meridian, etc.) remain unchanged.

Safety

Backup Recommended: While the tool only modifies 2 bytes, it’s good practice to keep backups of original files before batch processing.

The tool:

• Opens files in read-write binary mode (rb+)
• Only writes 2 bytes at the specific tag location
• Does not modify files that already have correct tags
• Exits with error if GeoTIFF structure is not found

Error Messages

Error	Meaning	Solution
Failed to open file	File not found or no read/write permissions	Check path and permissions
Did not find TIFF header	Not a GeoJP2 file or GeoTIFF data not in first 10KB	File may not be a GeoJP2 or is corrupted
Failed to find GEOKEYDIRECTORY tag	No GeoTIFF projection info	File lacks geospatial metadata
Unable to find target tag (3089 / CenterLat)	Already uses correct tag or different projection	No fix needed
StdParallel1GeoKey already exists	File already corrected	No action taken (v2 behavior)

HiRISE Background

HiRISE (High Resolution Imaging Science Experiment) is a camera aboard NASA’s Mars Reconnaissance Orbiter that captures images at resolutions up to 25-30 cm/pixel.

HiRISE Data Products

• Observation IDs: ESP_######_#### or PSP_######_####
• Standard Products: Red-band, color (IRB/RGB), and DTMs
• Projections: Typically Equirectangular for regional maps
• Formats: JPEG2000 for web distribution, ISIS cubes for processing

When to Use This Tool

Use fix_jp2_v2 for:

• Legacy HiRISE JP2 files (pre-2023) with projection issues
• Downloaded JP2 files that GDAL reports incorrect projection
• Files showing CenterLatGeoKey when StandardParallel1GeoKey is expected

Current HiRISE Data: Files processed after January 2023 by the HiRISE team should already have correct projection tags and won’t need fixing.

Verification Script

Check if a file needs fixing:

#!/bin/bash
# check_hirise_projection.sh

file="$1"
info=$(gdalinfo "$file" 2>&1)

if echo "$info" | grep -q "standard_parallel_1"; then
  echo "✓ $file: Projection is correct"
else
  echo "✗ $file: May need fixing"
fi

Usage:

chmod +x check_hirise_projection.sh
./check_hirise_projection.sh ESP_012345_1234_RED.JP2

Script Location

~/workspace/source/HiRISE_fix_jp2/fix_jp2_v2.cpp
~/workspace/source/HiRISE_fix_jp2/fix_jp2_v2.exe (Windows)

Additional Resources

• HiRISE Website
• HiRISE Data Portal
• More HiRISE Conversion Tips
• GDAL GeoJP2 Format

Credits

Author: Frank Warmerdam ([e-mail])
v2 Update: Trent Hare ([e-mail]) - January 2023

License: Public Domain

This tool is provided as-is for the planetary science community. Always validate outputs after processing.